﻿
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- saved from url=(0014)about:internet -->
<html xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:mssdk="winsdk" xmlns:script="urn:script" xmlns:build="urn:build" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="Description" content="Parsing Extension Arguments"/>
<meta name="MSHAttr" content="PreferredSiteName:MSDN"/>
<meta name="MSHAttr" content="PreferredLib:/library/windows/hardware"/>
<title>Parsing Extension Arguments</title>

<meta name="MS-HAID" content="EngExtCpp_DG_ee0ab1ba-1ede-4981-9200-ac2b0dbc6c03.xml"/>


<link rel="STYLESHEET" type="text/css" HREF="../common/backsdk4.css"/>





<style>
html,div { margin: 0; padding: 0;}

body {
	padding: 0px;
	margin: 0px;
	overflow: auto;
	height: 100%;
}

#winchm_template_button{
	float: right;
	width: 93px;
	top: 7px;
	position: relative;
	text-align: right;
	right: 5px;
	height: auto;
}

#winchm_template_top{
	padding: 0px;
	margin: 0px;
	border-bottom: 1px solid #9B9B9B;
	background-color: #B1CEFE;
}

#winchm_template_navigation{
	margin: 0px;
	padding-top: 7px;
	padding-left: 7px;
	padding-bottom: 3px;
	padding-right: 0px;
	font-size: 8.5pt;
	font-family: Arial, Helvetica, sans-serif;
	font-weight: normal;
	color: #585858;
}

#winchm_template_title{
	margin: 0px;
	padding-top: 4px;
	padding-left: 7px;
	padding-bottom: 7px;
	padding-right: 0px;
	font-size: 18px; 
	font-family: Verdana, Geneva, sans-serif;
	color: #363636;
}

#winchm_template_content{
	margin-top: 20px;
	margin-left: 15px;
	margin-bottom: 20px;
	margin-right: 15px;
	width: auto  !important;
	width: 100%;
}

#winchm_template_footer{
	border-width: 1px;
	border-color: #B1CEFE;
	border-top-style: solid;
	margin-top: 15px;
	margin-left: 15px;
	margin-bottom: 20px;
	margin-right: 15px;
	padding-top: 7px;
	padding-left: 0px;
	padding-bottom: 0px;
	padding-right: 0px;
	font-family: arial, helvetica, sans-serif;
	font-size: 8.5pt;
	color: #696969;
	width: auto;
	text-align: left;
}


#winchm_template_container{
	margin: 0px;
	padding: 0px;
	position: static;
	padding-bottom: 3px;
	overflow: auto;
	background-color: #FFFFFF;
}


@media print
{
#winchm_template_container{
	position: static;	
	margin: 0px;
	padding: 5px;
	
	width: auto;
	height: auto;
	overflow: auto;
}
#winchm_template_button{
visibility:hidden;
}
}

#winchm_template_navigation A:link	{text-decoration: none; color:#004080}
#winchm_template_navigation A:visited  {text-decoration: none; color: #004080}
#winchm_template_navigation A:active {text-decoration: none; color: #004080 }
#winchm_template_navigation A:hover {text-decoration: none;color: #0080FF}

A:link	{text-decoration: underline; color:#0033CC}
A:visited  {text-decoration: underline; color: #0033CC}
A:active {text-decoration: underline; color: #0033CC }
A:hover {text-decoration: underline;color: #FF0000;}
</style>
<script type="text/javascript">
function isMobile(){
Agent = window.navigator.userAgent;
if (Agent.indexOf("iPhone")>=1 || Agent.indexOf("iPad")>=1 || Agent.indexOf("iPod")>=1 || Agent.indexOf("Android")>=1){
return true;
}else{
return false;	
}

}
function d_onresize(){
if (window.navigator.userAgent.indexOf("MSIE")>=1){
document.getElementById('winchm_template_container').style.pixelWidth = document.body.offsetWidth - 3;
document.getElementById('winchm_template_container').style.pixelHeight = document.body.offsetHeight - document.getElementById('winchm_template_top').offsetHeight - 4;
}
document.getElementById('winchm_template_container').style.top = document.getElementById('winchm_template_top').offsetHeight + 'px';
}

function d_onbeforeprint(){
document.getElementById('winchm_template_container').style.width = 'auto';
document.getElementById('winchm_template_container').style.height = 'auto';
}

function d_onafterprint(){
d_onresize();
}

if(!isMobile()){

window.onload = d_onresize;
window.onresize = d_onresize;
window.onbeforeprint = d_onbeforeprint;
window.onafterprint = d_onafterprint;

document.write("<style>\n");
document.write("body {overflow: hidden;}\n");
document.write("#winchm_template_container {position: absolute;overflow: auto;top : 0px;right: 0px;bottom: 0px;left: 0px;}\n");
document.write("</style>\n");
}

</script>
</head>
<body><script language="JavaScript" type="text/JavaScript">
function syn(){
if(parent.nav.tree){
 if(parent.nav.tree.loaded){
  parent.nav.tree.selectNode(933);
 }else{
  setTimeout("syn()",500);
}
  }else{
  setTimeout("syn()",500);
  }}
if(parent!=self){
  setTimeout("syn()",100);
}else{
  parent.location.href = "../../index.htm?page=debugger/parsing_extension_arguments.htm";
}
originalOnload = window.onload;
if(originalOnload==null){
window.onload = function(){parent.contentLoaded = true;};
}else{
window.onload = function(){originalOnload();parent.contentLoaded = true;};
}
</script> 


<div id="winchm_template_top">
	<div id="winchm_template_button"><A href="building_extengcpp_extensions.htm" title="Previous topic"><img id="winchm_template_prev" alt="Previous topic" src="../template2/btn_prev_n.gif" border="0"></a><A href="typed_data.htm" title="Next topic"><img id="winchm_template_next" alt="Next topic" src="../template2/btn_next_n.gif" border="0"></a></div>
	<div id="winchm_template_navigation">Help &gt; 
<A href="introduction6.htm">Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)</A> &gt; <A href="debugging_resources.htm">Debugging Resources</A> &gt; <A href="debugger_engine_and_extension_apis.htm">Debugger Engine and Extension APIs</A> &gt; <A href="engextcpp_extensions.htm">EngExtCpp Extensions</A> &gt; <A href="engextcpp_extension_design_guide.htm">EngExtCpp Extension Design Guide</A> &gt; </div>
	<div id="winchm_template_title">Parsing Extension Arguments</div>
</div>
<div id="winchm_template_container">
	<div id="winchm_template_content"><div id="mainSection"><p>The EngExtCpp extension framework provides methods to aid in parsing the command-line arguments passed to an extension.  To take advantage of these methods, the extension must first declare the format of the command-line arguments in the <a href="#Bookmark938"><b>EXT_COMMAND</b></a> macro.</p>
<p>To bypass the command-line argument parsing done by the framework and let the extension itself parse the arguments, set the command-line description to <code>"{{custom}}"</code> and use the method <a href="#Bookmark961"><b>GetRawArgStr</b></a> to get the command-line arguments for parsing.</p>
<p>Command-line description strings will automatically be wrapped when printed, to fit the column width of the display.  However, newline characters can be embedded in the description strings - using '<code>\n</code>' - to start  new lines.</p>
<p>The command-line description can be <b>NULL</b> or the empty string.  If either occurs, it indicates that the extension command does not take any arguments.</p>
<h3><a id="command_line_description"></a><a id="COMMAND_LINE_DESCRIPTION"></a>Command-Line Description</h3>
<p>The description of the command-line arguments is a sequence that contains two types of components: directives and arguments.  The description can optionally contain one of each directive and can contain up to 64 arguments.</p>
<h3><a id="directives"></a><a id="DIRECTIVES"></a>Directives</h3>
<p>Directives specify how the arguments are parsed.  They are enclosed by double braces (<code>'{{'</code> and <code>'}}'</code>).  Each directive can optionally appear zero or one times in the string that describes the arguments.</p>
<p>The following directives are available:</p>
<p></p>
<dl>
<dt><a id="custom"></a><a id="CUSTOM"></a><code>custom</code></dt>
<dd>
<p>Turns off the parsing done by the extension framework and lets the extension perform its own parsing.</p>
</dd>
<dt><a id="l_str"></a><a id="L_STR"></a><code>l:str</code></dt>
<dd>
<p>Overrides the default long description of the command-line arguments.  The extension framework will use <i>str</i> for the full description of all the arguments.</p>
</dd>
<dt><a id="opt_str"></a><a id="OPT_STR"></a><code>opt:str</code></dt>
<dd>
<p>Overrides the default prefix characters for named commands.  The default value is <code>"/-"</code>, allowing '<code>/</code>' or '<code>-</code>' to be used as the prefix that identifies named arguments.</p>
</dd>
<dt><a id="s_str"></a><a id="S_STR"></a><code>s:str</code></dt>
<dd>
<p>Overrides the default short description of the command-line arguments.  The extension framework will use <i>str</i> for the short description of all the arguments.</p>
</dd>
</dl>
<p>Here are some examples of directives.  The following string is used by an extension command that parses its own arguments.  It also provides short and long descriptions for use with the automatic <b>!help</b> extension command:</p>
<pre class="syntax" xml:space="preserve"><code>{{custom}}{{s:&lt;arg1&gt; &lt;arg2&gt;}}{{l:arg1 - Argument 1\narg2 - Argument 2}}</code></pre>
<p>The following string changes the argument option prefix characters to '<code>/</code>' or '<code>-</code>'.  With this directive, the arguments will be specified using '<code>+arg</code>' and '<code>:arg</code>' instead of '<code>/arg</code>' and '<code>-arg</code>':</p>
<pre class="syntax" xml:space="preserve"><code>{{opt:+:}}</code></pre>
<h3><a id="arguments"></a><a id="ARGUMENTS"></a>Arguments</h3>
<p>Arguments can be of two types: named and unnamed.  Unnamed arguments are read positionally.  Both types of argument also have a display name, used by the help command.</p>
<p>Argument descriptions are enclosed by single braces (<code>'{'</code> and <code>'}'</code>).  </p>
<p>Each argument description has the following syntax:</p>
<pre class="syntax" xml:space="preserve"><code>{[optname];[type[,flags]];[argname];[argdesc]}</code></pre>
<p>where:</p>
<p></p>
<dl>
<dt><a id="optname"></a><a id="OPTNAME"></a><i>optname</i></dt>
<dd>
<p>The name of the argument.  This is the name used in commands and in methods that fetch arguments by name.  This name is optional.  If it is present, the argument becomes a "named argument"; it can appear anywhere on the command-line and is referenced by name.  If it is not present, the argument becomes an "unnamed argument"; its position on the command-line is important and it is referenced by its position relative to the other unnamed arguments.</p>
</dd>
<dt><a id="type"></a><a id="TYPE"></a><i>type</i></dt>
<dd>
<p>The type of the argument.  This affects how the argument is parsed and how it is retrieved. The <i>type</i> parameter can have one of the following values:</p>
<p></p>
<dl>
<dt><a id="b"></a><a id="B"></a>b</dt>
<dd>
<p>Boolean type.  The argument is either present or not present.  Named Boolean arguments can be retrieved using <a href="#Bookmark953"><b>HasArg</b></a>.</p>
</dd>
<dt><a id="e_d__s__bits_"></a><a id="E_D__S__BITS_"></a>e[d][s][bits]</dt>
<dd>
<p>Expression type.  The argument has a numeric value.  Named expression arguments can be retrieved using <a href="#Bookmark952"><b>GetArgU64</b></a> and unnamed expression arguments can be retrieved using <a href="#Bookmark949"><b>GetUnnamedArgU64</b></a>.

		     </p>
<p></p>
<dl>
<dt><a id="d"></a><a id="D"></a>d</dt>
<dd>
<p>The expression is limited to the next space character in the argument string.  If this is not present, the expression evaluator will consume characters from the command line until it determines that it reached the end of the expression.</p>
</dd>
<dt><a id="s"></a><a id="S"></a>s</dt>
<dd>
<p>The value of the expression is signed.  Otherwise, the value of the expression is unsigned.</p>
</dd>
<dt><a id="bits"></a><a id="BITS"></a>bits</dt>
<dd>
<p>The number of bits in the value of the argument.  The maximum value for <i>bits</i> is 64.</p>
</dd>
</dl>
</dd>
<dt><a id="s"></a><a id="S"></a>s</dt>
<dd>
<p>String type.  The string is limited to the next space character.  Named string arguments can be retrieved using <a href="#Bookmark951"><b>GetArgStr</b></a> and unnamed string arguments can be retrieved using <a href="#Bookmark948"><b>GetUnnamedArgStr</b></a>.</p>
</dd>
<dt><a id="x"></a><a id="X"></a>x</dt>
<dd>
<p>String type.  The argument is the rest of the command line.  The argument is retrieved using <b>GetArgStr</b> or <b>GetUnnamedArgStr</b>, as with the s string type.</p>
</dd>
</dl>
</dd>
<dt><a id="flags"></a><a id="FLAGS"></a><i>flags</i></dt>
<dd>
<p>The argument flags.  These determine how the argument will be treated by the parser. The <i>flags</i> parameter can have one of the following values:</p>
<p></p>
<dl>
<dt><a id="d_expr"></a><a id="D_EXPR"></a>d=expr</dt>
<dd>
<p>The default value of the argument.  If the argument is not present on the command line, then the argument is set to <i>expr</i>.  The default value is a string that is parsed according to the type of the argument.</p>
</dd>
<dt><a id="ds"></a><a id="DS"></a>ds</dt>
<dd>
<p>The default value will not be displayed in the argument description provided by the help.</p>
</dd>
<dt><a id="o"></a><a id="O"></a>o</dt>
<dd>
<p>The argument is optional.  This is the default for named arguments.</p>
</dd>
<dt><a id="r"></a><a id="R"></a>r</dt>
<dd>
<p>The argument is required.  This is the default for unnamed arguments.</p>
</dd>
</dl>
</dd>
<dt><a id="argname"></a><a id="ARGNAME"></a><i>argname</i></dt>
<dd>
<p>The display name of the argument.  This is the name used by the automatic <b>!help</b> extension command and by the automatic <b>/?</b> or <b>-?</b> command-line arguments.  Used when printing a summary of the command-line options.</p>
</dd>
<dt><a id="argdesc"></a><a id="ARGDESC"></a><i>argdesc</i></dt>
<dd>
<p>A description of the argument.  This is the description printed by the automatic <b>!help</b> extension and by the automatic "<b>/?</b>" or "<b>-?</b>" command-line arguments.</p>
</dd>
</dl>
<p>Here are some examples of argument descriptions.  The following expression defines a command which takes a single optional expression argument.  The argument must fit in 32 bits. If the argument isn't present on the command line, the default value of 0x100 will be used.</p>
<pre class="syntax" xml:space="preserve"><code>{;e32,o,d=0x100;flags;Flags to control command}</code></pre>
<p>The following expression defines a command with an optional Boolean "<b>/v</b>" argument and a required unnamed string argument.</p>
<pre class="syntax" xml:space="preserve"><code>{v;b;;Verbose mode}{;s;name;Name of object}</code></pre>
<p>The following expression defines a command that has an optional named expression argument <b>/oname </b><i>expr</i> and an optional named string argument <b>/eol </b><i>str</i>.  If <b>/eol</b> is present, its value will be set to the remainder of the command line and no further arguments will be parsed.</p>
<pre class="syntax" xml:space="preserve"><code>{oname;e;expr;Address of object}{eol;x;str;Commands to use}</code></pre>
<h3><a id="command_line"></a><a id="COMMAND_LINE"></a>Command Line</h3>
<p>The following is a list of some ways that arguments are parsed on the command line:</p>
<ul>
<li>
<p>The values of named expression and string arguments follow the name on the command line. For example, <b>/name </b><i>expr</i> or <b>/name </b><i>str</i>.</p>
</li>
<li>
<p>For named Boolean arguments, the value is true if the name appears on the command line; false otherwise.</p>
</li>
<li>
<p>Multiple single-character-named Boolean options can be grouped together on the command line. For example, "/a /b /c" can be written using the shorthand notation "/abc" (unless there is already an argument named "abc").</p>
</li>
<li>
<p>If the command line contains the named argument "?" - for example, "/?" and "-?" - the argument parsing ends, and the help text for the extension is displayed.</p>
</li>
</ul>
<h3><a id="parsing_internals"></a><a id="PARSING_INTERNALS"></a>Parsing Internals</h3>
<p>Several methods are used by the argument parser to set arguments. </p>
<p>The method <a href="#Bookmark955"><b>SetUnnamedArg</b></a> will change the value of an unnamed argument.  And, for convenience, the methods <a href="#Bookmark956"><b>SetUnnamedArgStr</b></a> and <a href="#Bookmark957"><b>SetUnnamedArgU64</b></a> will set unnamed string and expression arguments respectively.</p>
<p>Similar methods exist for named arguments. <a href="#Bookmark958"><b>SetArg</b></a> is used to change the value of any named argument and <a href="#Bookmark959"><b>SetArgStr</b></a> and <a href="#Bookmark960"><b>SetArgU64</b></a> are used for named string and expression arguments respectively.</p></div></div>	
	<div id="winchm_template_footer">Copyright &copy; 2019. All rights 
reserved. (To change the copyright info, just edit it in template.)</div>
</div>

</body>
</html>
